home *** CD-ROM | disk | FTP | other *** search
/ Popular Request / By Popular Request (Arsenal Computer)(SysOptics Distribution System).ISO / amiga4 / tdclk201.lha / TDClick2.doc < prev    next >
Text File  |  1994-03-22  |  20KB  |  480 lines
  1.  
  2.  
  3.  
  4.                             TDClick Version 2.01
  5.                    Copyright Mar. 1994 by Elton VonCannon
  6.                             All rights reserved.
  7.  
  8.  
  9.  
  10. ----------------------------------------------------------------------------
  11.                               WHAT IS TDClick?
  12. ----------------------------------------------------------------------------
  13.  
  14. TDClick is a program written in AmigaE that allows user configurable buttons
  15. on  TrapDoor's  (or  any  other)  public screen.  Its intended purpose is to
  16. launch  external programs and scripts that ultimately control some aspect of
  17. TrapDoor (although it's not limited to this).
  18.  
  19.  
  20.  
  21. ----------------------------------------------------------------------------
  22.                                 DISCLAIMER:
  23. ----------------------------------------------------------------------------
  24.  
  25. This  software  is  provided  "as-is",  without warranty of any kind, either
  26. expressed  or  implied.   In no event will I, Elton VonCannon, be liable for
  27. direct, indirect, incidental or consequential damages or data loss resulting
  28. from  the  use  or  application of this software.  The entire risk as to the
  29. results and performance of this software is assumed by you, the user.
  30.  
  31.  
  32.  
  33. ----------------------------------------------------------------------------
  34.                           LICENSING REQUIREMENTS:
  35. ----------------------------------------------------------------------------
  36.  
  37. You  are authorized to distribute the archive for any non-commercial purpose
  38. as long as its contents remain unaltered.  Any commercial distribution, with
  39. the exception of Fred Fish, requires the permission of the author.
  40.  
  41. If  you  use this program, let me know.  Public response can keep me working
  42. on  TDClick, otherwise what's the point?  My address is listed at the end of
  43. this document.
  44.  
  45.  
  46.  
  47. ----------------------------------------------------------------------------
  48.                             SYSTEM REQUIREMENTS:
  49. ----------------------------------------------------------------------------
  50.  
  51. TDClick  requires  ReqTools.library  version 38 or greater and should run on
  52. all  systems using Kickstart 2.04 and above.
  53.  
  54.  
  55.  
  56. ----------------------------------------------------------------------------
  57.                                INSTALLATION:
  58. ----------------------------------------------------------------------------
  59.  
  60. Copy TDClick and its configuration file wherever you want.  I recommend that
  61. it  be  placed  in  the  same directory as TrapDoor, but it isn't necessary.
  62. You'll  also  need to edit the configutation file to conform to your system.
  63. This  is  described  below.   You  will also need to insure that TrapDoor is
  64. configured (in TrapDoor.cfg) thusly:
  65.  
  66. PUBSCREENNAME "TrapDoor"    ; Note:  You can also comment this line out,
  67.                             ; since it is the default.  DO NOT SET TO ""!
  68.                             ; If you use another PUBSCREENNAME, you can
  69.                             ; use the "-s" option to inform TDClick of
  70.                             ; the  new name.
  71. SCREENMODE PUBLIC           ; This is required.
  72. INTERLACE                   ; Not required, but you'll have room for
  73.                             ; more buttons.
  74.  
  75.  
  76.  
  77.  
  78. ----------------------------------------------------------------------------
  79.                              STARTING TDClick:
  80. ----------------------------------------------------------------------------
  81.  
  82. Run  TrapDoor  first,  so  that  its  screen will be available.  "Cd" to the
  83. directory  that  TDClick  is  in,  and  type  "run  TDClick"  from  a shell.
  84. (Preferrably  one  that's open on TrapDoor's screen.) You can start one like
  85. this:
  86.   NewShell WINDOW "CON:0/12/572/110/TDShell/CLOSE/SCREEN TrapDoor"
  87.  
  88. NOTE:   There is a script file included in the TDClick archive that'll start
  89. everything  for  you.   To  use  it,  you need to have TDClick, TDClick.cfg,
  90. TDStartup  and  TDShell.Startup  in  the  current  directory.   First  start
  91. TrapDoor normally then type "TDStartup" and everything should be started for
  92. you.
  93.  
  94.  
  95. If  you don't re-direct TDClick's output when you start it, any command that
  96. TDClick  executes  will  use  TDClick's  parent  window for its input/output
  97. unless  you  configure  a custom window for the command.  This means that in
  98. order  for  you  to [BREAK] a program started by TDClick, the correct window
  99. will have to be activated first.
  100.  
  101. NOTE:   TDClick's  parent  window will be the shell that you started TDClick
  102. from.   If  you  start  it  from a background CLI or re-direct its output to
  103. NIL:,  there  will  be no window.  There are ways around this.  Consult your
  104. AmigaDos manuals for more information.
  105.  
  106. The  stack size is unimportant for TDClick itself, since TDClick will create
  107. and  use  its own stack, but the stack should be set high enough for any CLI
  108. commands  that  you  intend  to execute with TDClick.  CLI commands that are
  109. started  by  TDClick  will use the same path that was in effect when TDClick
  110. was started.
  111.  
  112. When  you  start  TDClick,  you  can  indicate  other  names  for  TDClick's
  113. configuration  file,  its  public  screen  name,  as  well  as  the  initial
  114. coordinates  for  the  top left corner of the window that TDClick will open.
  115. There is also an option for launching programs asynchronously.
  116.  
  117. Typing "TDClick ?" will provide the following usage info.
  118.  
  119.  
  120. Usage:
  121.  TDClick2 [-C config] [-S screen] [-X xpos] [-Y ypos] [-ZX xpos] [-ZY ypos]
  122.           [-A TRUElFALSE] [-B TRUElFALSE]
  123.  
  124. Where:  -C  (TDClick.cfg).Specifies the configuration filename.
  125.         -S  (TrapDoor)....the name of the public screen that TDClick
  126.                           will open its window on.
  127.         -X  (520).........the position of the left edge of the window.
  128.         -Y  (12)..........the position of the top of the window.
  129.         -ZX (520).........the position of the left edge of the window
  130.                           when ZOOMED out.
  131.         -ZY (0)...........the position of the top of the window when
  132.                           ZOOMED out.
  133.         -A  (FALSE).......Async: A flag that if TRUE, tells TDClick to
  134.                           execute all of its commands Asynchronously.
  135.         -B  (FALSE).......Background: A flag that if TRUE, TDClick will not
  136.                           activate its window upon startup.
  137.  
  138. NOTE: The value shown in parenthesis is the default for that parameter.
  139.  
  140. All arguments are optional and can be specified in any order.
  141. All arguments must be seperated by at least one space.
  142.  
  143.  
  144.  
  145. When TDClick is run, it will attempt to open a window 120 pixels wide on the
  146. specified  (or TrapDoor's) public screen.  The height of TDClick's window is
  147. determined  by  the  number  of  buttons in your configuration file.  If you
  148. specify too many buttons, TDClick will notify you.
  149.  
  150. TIP:   If  you  want TDClick to open its window on the rightmost side of the
  151. screen, just specify something huge like:  "-X 3000".  TDClick will position
  152. its  window  as  close  to the coordinate as it can, which will be the right
  153. side of the screen.  :)
  154.  
  155. If  you  need  more  buttons  than TDClick can display, you can run multiple
  156. copies  of TDClick, with each instance using a different configuration file.
  157. The  first few characters of the config file's name will appear in TDClick's
  158. title  bar.   This  helps  identify  which  instance  of  TDClick is using a
  159. particular configuration, if you're running multiple copies of TDClick.
  160.  
  161.  
  162.  
  163.  
  164. ----------------------------------------------------------------------------
  165.                                USING TDClick:
  166. ----------------------------------------------------------------------------
  167.  
  168. After  TDClick is running, you're on your own.  The only pre-defined gadgets
  169. are:
  170.  
  171.      Close:  A standard  Intuition gadget.  When  clicked, this
  172.              causes TDClick to close its window and exit.  Note
  173.              that if TDClick's  window is the last  window open
  174.              on its screen, it'll close the screen too.
  175.  
  176.      Zoom:   A standard Intuition gadget. This gadget will make
  177.              TDClick's  window very  small.  This is useful for
  178.              quickly  making  as  much of TrapDoor's windows as 
  179.              visable as  possible.  Clicking  this gadget again
  180.              will make the window full size again.
  181.              Note that  you can set the default zoomed position
  182.              of the window by using the -ZX and -ZY options.
  183.  
  184.  
  185. Clicking any other button causes TDClick to attempt to execute that button's
  186. user  defined  CLI  command.   Defining  the  buttons  is  explained  in the
  187. "Configuration File" section.
  188.  
  189.  
  190.  
  191. ----------------------------------------------------------------------------
  192.                               TDClick's MENUS:
  193. ----------------------------------------------------------------------------
  194.  
  195.      Open:   Enables you to open a new configuration file.
  196.      Async:  Toggles asyncronous execution mode on/off.
  197.      Help:   Toggles help mode on/off. (Also useful for debugging.)
  198.      About:  Displays some information about TDClick.
  199.      Quit:   Causes TDClick to close its window and exit.
  200.  
  201.  
  202. Selecting  "Open"  will  bring  up  a file requestor that will enable you to
  203. select a configuration file for TDClick to load.
  204.  
  205.  
  206. Selecting  "Async"  will  toggle  asyncronous  execution  mode on/off.  When
  207. "Async"  is  enabled  (indicated  by  a checkmark in the menu), TDClick will
  208. execute all of the user defined commands asyncronously.  This may not always
  209. be  desirable.   That's  why  I've allowed the user to set it however he/she
  210. wishes.
  211.  
  212. NOTE:   If  Async  is  enabled  and  multiple  commands are specified for an
  213. individual  button, a temporary script will be created in t:  and the entire
  214. script  will  be  executed asynchronously.  This is also true of any command
  215. string  that  contains  the  \G  operator  that  is  described below.  These
  216. temporary  scripts are overwritten as necessary and deleted whenever TDClick
  217. loads  a  new  configuration  as  well  as  when TDClick exits.  It executes
  218. AmigaDos' delete command to perform the actual deletion.
  219.  
  220.  
  221. Selecting  "Help"  will  toggle  help  mode  on/off.   When "Help" is active
  222. (indicated  by  a  checkmark in the menu), no commands will be executed.  If
  223. you  click a user button that normally brings up a requester, that requester
  224. will  be brought up before displaying that button's command string.  This is
  225. so that you can see exactly what effect a requester has on a command string.
  226. Cancelling  the  requester  will  produce  no  help display for that command
  227. string, since you will have cancelled the entire operation.
  228.  
  229.  
  230. Selecting "About" will display some information about TDClick.
  231.  
  232.  
  233. Selecting "Quit" will terminate TDClick.
  234.  
  235.  
  236.  
  237.  
  238. ----------------------------------------------------------------------------
  239.                           THE CONFIGURATION FILE:
  240. ----------------------------------------------------------------------------
  241.  
  242. TDClick's configuration file contains the text for TDClick's buttons as well
  243. as the commands that TDClick will execute whenever that button is clicked.
  244.  
  245.  
  246. These rules apply to the text in the configuration file:
  247.  
  248.     a. All button and command text can start at any column of a line.
  249.        ie: Leading spaces and tabs are ignored.
  250.     b. If a line contains a  semicolon,  the rest of the line will be
  251.        ignored... this is useful for adding comments to a config.
  252.     c. Blank lines are ignored.
  253.     d. BUTTON  NAMES MUST  ALWAYS BE LESS THAN 13 characters! TDClick
  254.        will warn you and stop processing a configuration file,  if it
  255.        encounters a button's name that is too long.
  256.     e. Do not put  "too many"  buttons in the config file. The actual
  257.        number of  buttons  that TDClick can handle is dependent upon:
  258.          1.  Whether or not you use interlace mode.
  259.          2.  Your overscan settings, etc.
  260.          3.  A  hardcoded  maximum of 80 buttons.  (You will never be
  261.              able to see them all unless you have a HUGE screen.)
  262.              Note: TDClick will still display all the buttons that it
  263.              can fit on the screen. Of course, you will never see any
  264.              that are "off screen". :)
  265.  
  266.  
  267.  
  268. The FORMAT of the configuration file is:
  269.   button's name
  270.   command to execute
  271.  
  272.   another button's name
  273.   another command to execute
  274.  
  275.   yet, another button's name
  276.   yet another command to execute
  277.  
  278.   etc...
  279.  
  280.  
  281. Actually,  it's  very  simple.   The first line contains the text for a user
  282. definable  button.   The  next  line  contains the CLI command that you want
  283. executed  when  the  button is clicked.  (Referred to as a button's "command
  284. string".) The example configuration file, "TDClick.cfg" that was distributed
  285. in  TDClick2's  archive  should  help  clarify  things,  if  you  find  this
  286. description  unintelligible.   It's  simpler  to do it than it is to explain
  287. how.
  288.  
  289.  
  290.  
  291.  
  292. ----------------------------------------------------------------------------
  293.                           THE BACKSLASH OPERATORS:
  294. ----------------------------------------------------------------------------
  295.  
  296. There  a few "backslash" operators that TDClick will interpret when a button
  297. containing one is clicked.  These are:
  298.  
  299.    \F  Brings up a file requester.
  300.    \S  Brings up a string requester.
  301.    \N  Command seperator. (Allows multiple commands per button.)
  302.    \W  Forces a command to open its own window.
  303.    \G  Opens a single global window for multiple commands.
  304.    \\  Forces TDClick to ignore a single backspace.
  305.  
  306. No  backslash  operator  is  case  sensitive and any number can be contained
  307. within a single command string.
  308.  
  309. All  operators,  except  \\  and  \n,  will  allow  a  user definable string
  310. parameter  to  be  specified  by placing the string inside the curly braces,
  311. "{}".   If you use the curly braces to indicate a string, the first one MUST
  312. join  the  operator.   In  other  words,  there can be no intervening spaces
  313. between an operator and the first curly brace, "{".
  314.  
  315. For example:  \s{Mystuff} will work, while:  \s {MyStuff} will not.
  316.  
  317.  
  318.  
  319. THE MULTIPLE COMMAND OPERATOR: \n
  320.  
  321. You  can  specify multiple commands per button by seperating the commands in
  322. the  command string with "\n".  If "Async" is enabled, TDClick will create a
  323. unique script in t:  and execute the entire script asyncronously.
  324.  
  325.  
  326.  
  327. THE WINDOW OPERATORS: \w and \g
  328.  
  329. You  can  force  a  command to open a window for its input/output by placing
  330. "\w" in the command string.  You can specify the window's position, size and
  331. title by placing them inside curly braces like this:
  332.  
  333. \w{10/20/480/100/MyWindow}
  334.  
  335. Normally  the window will close when the command that's using it terminates,
  336. but you can force the window to remain open until you click the close gadget
  337. by placing "/WAIT" after the window's title.
  338.  
  339. ie: List Mail:Inbound \w{10/20/500/180/List window./WAIT}
  340.  
  341. This will list "Mail:Inbound" using a custom window.  The window will remain
  342. open until you click the close gadget.
  343.  
  344. If  you  use  \w  without specifying any window parameters, a default window
  345. will be opened for the command.
  346.  
  347. While  the global window operator (\g) allows the same options as the normal
  348. window operator, it has one major difference:  it does not open a window for
  349. each command, it opens singgle a window for multiple commands.
  350.  
  351. ie:   \g{0/0/100/30}echo "hello"\necho "y'all"
  352. This would open a single window for BOTH echo commands' messages.
  353.  
  354. NOTE:   You  may  notice  a  similiarity  between TDClick's windows and CON:
  355. windows.   This  is  because  TDClick translates your window parameters into
  356. CON:  parameters before executing the command string.
  357.  
  358.  
  359.  
  360. THE REQUESTER OPERATORS: \s and \f
  361.  
  362. You  can  instruct  TDClick  to  "pop  up"  a  requester in order to provide
  363. arguments  for a CLI command (or even to BE the command).  Any text returned
  364. by the requester will be inserted into the command string at the location of
  365. the  \s or \f operator.  Additionally, the \f and \s options themselves have
  366. two  text  options.   These  are contained within the curly braces, "{}" and
  367. seperated  by  the  vertical bar, "|".  The first option is the text for the
  368. requester's  title,  and  the  second  option  is  the  default text for the
  369. requester.
  370.  
  371. For example:  "TrapTell \s{Tell TrapDoor to set:|FASTEMSI}"
  372.  
  373. This  will  bring  up  a string requester with a title of, "Tell TrapDoor to
  374. set:"  and  the  requester's default text will be "FASTEMSI".  If you do not
  375. change  the  default  text, the resulting command string will be:
  376. "TrapTell FASTEMSI".
  377.  
  378. A more useful example might be:
  379. "rexx:rx call.rexx \s{Call who?|1:3648/101}"
  380.  
  381. When  a button containing this command string is clicked, a string requester
  382. titled  "Call who?" will be displayed with the default text of "1:3648/101".
  383. This   can   be  very  useful  for  infrequently  called  nodes  or  points.
  384. (Frequently called nodes can be given their own button without a requester.)
  385.  
  386. Note  that  if  you simply press the return key on an empty requester, it is
  387. the  same  as  cancelling the requester.  If you do not want this to happen,
  388. you can enter a default text consisting of a single space.
  389.  
  390. Usage  of  the  file  requester  operator,  "\f"  is identical to the string
  391. requester  except  that  the  default  text  parameter  is used as a default
  392. path/filename.
  393.  
  394.  
  395.  
  396. THE DOUBLE BACKSLASH OPERATOR: \\
  397.  
  398. Use this, if you want to pass a single backslash to a CLI command.
  399.  
  400.  
  401. See the included TDClick.cfg for more examples.
  402.  
  403.  
  404.  
  405.  
  406.  
  407. ----------------------------------------------------------------------------
  408.                               ERROR MESSAGES:
  409. ----------------------------------------------------------------------------
  410.  
  411. If  you didn't redirect its output at startup, TDClick should inform you, if
  412. an  error  occurs  while opening ReqTools.library.  All other error messages
  413. will  be  displayed  via  requesters.   Hopefully the error messages will be
  414. self-explanatory.
  415.  
  416.  
  417.  
  418. ----------------------------------------------------------------------------
  419.                               HIDDEN FEATURES:
  420. ----------------------------------------------------------------------------
  421.  
  422. TDClick  now  goes to extreme measures to check for a large number of errors
  423. of all kinds (including possible programming errors).  Sometimes I feel that
  424. it  does  more  error  checking  than processing.  However, if you feel that
  425. there  are  any  bugs,  please  send  me  a DETAILED report of what you feel
  426. TDClick   is  doing  wrong.   (Just  saying  "It  don't  work."  is  useless
  427. information to me.) Here are a few things that aren't bugs:
  428.  
  429.     TDClick  does  not  allow  spaces in the path or name of its config
  430.     file.  This isn't a bug.  It's just a brain-dead parser.  :)
  431.  
  432.     Sometimes TDClick will appear to ignore clicks on its buttons.  This
  433.     is  because  TDClick  is  waiting for a command to finish execution.
  434.     These  button  clicks will be queued and executed after the previous
  435.     command  finishes.  If you  want commands to run asynchronously, you
  436.     must put the word  "run"  before  each  command in the configuration
  437.     file  or start TDClick with the -A TRUE  option,  or just toggle the
  438.     "Async" menu item on.
  439.  
  440.     TDClick  ignores  the  system  stack  and sets its own.  Some  stack
  441.     monitoring  programs mistakenly assume this to mean that TDClick has
  442.     a stack problem.
  443.  
  444.  
  445.  
  446. ----------------------------------------------------------------------------
  447.                                IN CONCLUSION:
  448. ----------------------------------------------------------------------------
  449.  
  450. If  I  am  presented  with any enhancement suggestions, I'll consider adding
  451. them.  I welcome all comments and suggestions.
  452.  
  453.  
  454. Enjoy!
  455. Elton VonCannon, author of TDClick.
  456.  
  457.  
  458. I can be reached at:
  459.  
  460.                    FidoNet:     1:3648/101.2
  461.  
  462.                    Postal Mail: Elton VonCannon
  463.                                 919 Macon St.
  464.                                 Asheboro, NC
  465.                                        27203
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472. ----------------------------------------------------------------------------
  473.                                    NOTES:
  474. ----------------------------------------------------------------------------
  475.   TrapDoor is copyrighted software by Maximilian Hantsch and Martin Laubach.
  476.   ReqTools is copyrighted software by Nico Francois.
  477.  
  478.  
  479.  
  480.